Microsoft CodeView and Utilities
================================
CHAPTER 4 ___ CODEVIEW EXPRESSIONS
(First half)

CodeView command arguments are expressions that can include symbols, constant
numbers, operators, and registers.  Arguments can be simple machine-level
expressions that directly specify an address or range in memory or they can be
source-level expressions that correspond to operators and symbols used in
Microsoft C, FORTRAN, BASIC, Pascal or the Macro Assembler.  For each high-
level language (C, FORTRAN, BASIC, and Pascal), CodeView has an expression
evaluator that computes the value of source-level expressions.

Each of the four expression evaluators has a different set of operators and
rules of precedence.  However, the basic syntax for registers, addresses, and
line numbers is the same regardless of the language.  You can always change
the expression evaluator.  fIf you specify a language other than the one used
in the source file, then the expression evaluator will still recognize your
program symbols, if possible. (C and FORTRAN, however, will not accept BASIC
type tage.)  If you are debugging an assembly routine called from BASIC OR
FORTRAN, then you may want to choose the language of the main program, rather
than C, which is default for assembly programs.

If the Auto option is on, then the debugger examines the file extension of
each new source file you trace through.  Both C and assembly modules cause the
debugger to select C as the expression evaluator.

This chapter deals first with the expressions specific to each language.
Line-number expressions are presented next; they work the same way regardless
of the language.  Then, register and address expressions are presented;
generally, these do not have to be mastered unless you are doing assembly-
level debugging.  Finally, the chapter describes how to switch the expression
evaluator.
----
Note
----
When you use a variable in an expression where that variable is not
defined, the CodeView debugger displays the  message UNKNOWN SYMBOL.  For
example, the message appears if you reference a local variable outside the
function where the variable is defined.
====

4.1  C Expressions

The C expression evaluator uses a subset of the most commonly used C oper-
ators.  It also supports the colon operator (:), which is described in Section
4.7.2, "Addresses," and the three memory operators (BY, WO, and DW), which are
discussed in Section 4.8.  The memory operators are primarily useful for
debugging assembly source code.  The CodeView C-expression operators are
listed in Table 4.1 in order of precedence.  The superscripts a, b, and c
indicate explanatory footnotes.

Table 4.1 - CodeView C-Expression Operators
------------------------
Precedence	Operators
------------------------
(Highest)
1			() [] ->.
2			!~-b (type) ++ -- *b &c sizeof
3			*b / % :
4			+ -a
5			< > <= >=
6			== !=
7			&&
8			||
9			= += -+ *= /= %=
10			BY WO DW
(Lowest)

a	The minus sign with precedence 2 is the unary minus indicating the sign of
	a number; the minus with precedence 4 is a binary minus indicating
	subtraction.
b	The asterisk with precedence 2 is the pointer operator; the asterisk with
	precedence 3 is the multiplication operator.
c	The ampersand with precedence 2 is th eaddress-of operator.  The ampersand
	as a bitwise AND operator is not supported by the CodeView debugger.

See the Microsoft C Compiler Language Reference for a description of how C
operators can be combined with identifiers and constants to form expressions.
With th eC-expression evaluator, the period (.) has its normal use as a member
selection operator, but it also has an extended use as a specifier of local
variable in parent functions.  The syntax is shown below:

function.variable

The function must be a high level language function and the variable must be a
local variable within the specified function.  The variable cannot be a
register variable.  For example, you can use the expression main.argc to refer
to the local variable argc when you are in a function that has been called by
main.

The type operator (used in type casting) can be any of the predefined C types.
The CodeView debugger limits casts of pointer types to one level of indirec-
tion.  For example, (char  *) sym is accepted, but  (char  **) sym is not.

When a C expression is used as an argument with a command that takes multiple
arguments, the expression should not have any internal spaces.  For example,
count+6 is allowed, but count + 6 may be interpreted as three separate argu-
ments. Some commands (such as the Display Expression command) do permit spaces
in expressions.

4.1.1  C Symbols

<*> Syntax

name
A synbol is a name that represents a register, a segment address, an offset
address, or a full 32-bit address.  At the C source level, a symbol is a
variable name or the name of a function.  Symbols (also called identifiers)
follow the naming rules of the C compiler. Note that although CodeView command
letters are not case sensitive, symbols given as arguments are case sensitive
(unless you have turned off case sensitivity with the Case Sense selection
from the Options menu).

In assembly language output or in output from the Examine Symbols command, the
CodeView debugger displays some symbol names in the  object code format
produced by the Microsoft C Compiler.  This format includes a leading under-
score.  For example, the function main is displayed as _main.  Only global
labels (such as procedure names) are shown in this format.  You do not need to
include the underscore when specifying such a symbol in CodeView commands.
Labels within library routines are sometimes displayed with a double under-
score (__chkstk).  You must use two leading underscore when accessing these
labels with CodeView commands.

4.1.2  C Constants

<*> Syntax

digits		Default radix
O digits		Octal radix
Ox digits		Hexadecimal radix
On digits		Decimal radix

Numbers used in CodeView commands represent integer constant.  They are made
up of octal, hexadecimal, or decimal digits, and are entered in the current
input radix.  The C language format for entering numbers of different radixes
can be used to override the current input radix.

The default radix for the C expression evaluator is decimal.  However, you can
use the Radix command (N) to specify an octal or hexadecimal radix, as
explained in Section 11.3, "Radix Command."

If the current radix is 16 (hexadecimal) or 8 (octal), you can enter decimal
numbers in the special CodeView format On digits.  For example, enter 21
decimal as On21.

With radix 16, it is possible to enter a value or argument that could be
interpreted either as a symbol or as a hexadecimal number.  The CodeView
debugger resolves the ambiguity by searching first for a symbol (identifier)
with that name.  If no symbol is found, the debugger interprets the value as a
hexadecimal number.  If you want to enter a number that overrides an existing
symbol, use the hexadecimal format (Ox digits).

For example, if you enter abc as an argument when the program contains a
variable or function named abc, the CodeView debugger interprets the argument
as the symbol.  If you want to enter abc as a number, enter it as  Oxabc.

Table 4.2 shows how a sample number (63 decimal) would be represented in each
radix.

Table 4.2   -  C Radix Examples
---------------------------------------------------
Input Radix	Octal		Decimal		Hexadecimal
--------------------------------------------------------
8		77		On63		Ox3F
10		O77		63		Ox3F
16		O77		On63		3F

4.1.3  C Strings

<*> Syntax

"null-terminated-string" 

Strings can be specified as expressions in the C format.  You can use C escape
characters within strings.  For example, double quotation marks within a
string are specified with the escape character \".

<*> Example

>EA message "This \"string\" is okay."

The example uses the Enter ASCII command (EA) to enter the given string into
memory starting at the address of the variable   message.

4.2  FORTRAN Expressions

The FORTRAN expression evaluator uses a subset of the most commonly used
FORTRAN operators.  It also supports two additional operators, the period (.)
and colon (:).  A number of FORTRAN intrinsic functions, listed in Section
4.2.4, are also supported.  FORTRAN function calls are permitted, but state-
ment function names and COMMON block names are not. (Note that these limit-
ations only apply to the arguments of CodeView commands.  They do not apply to
the source program, which can contain any valid FORTRAN expression.)  The
CodeView FORTRAN operators are listed in Table 4.3 in order of precedence.

Table 4.3  - CodeView FORTRAN Operators
-----------------------
Precedence	Operator
-----------------------
(Highest)
1		()
2		.  :
3		Unary + -
4		* /
5		Binary + -
6		.LT. .LE. .EQ. .NE. .GT. .GE.
7		.NOT.
8		.AND.
9		.OR.
10		.EQV. .NEQV.
11		=
(Lowest)

The FORTRAN expression evaluator does not support the character concatenation
operator (//) or the exponentiation operator (**).  Relational operators are
not supported for string variables or constants.

The order and precedence with which the CodeView debugger evaluates FORTRAN
expressions are the same as in the Microsoft FORTRAN language.  See Chapter 2
of the Microsoft FORTRAN Compiler Language Reference for a description of how
FORTRAN operators can be combined with symbols and constants to form
expressions.

The colon operator (:) may be used when specifying a memory address.  It acts
as a segment:offset operator, as described in Section 4.7.2,
"Addresses."

In the CodeView debugger, the period (.) has an extended use as a specifier of
local variables in parent routines.  The syntax is shown below:

routine.variable

The routine must be a high-level language routine and the variable must be a
local variable within the specified routine.  For example, you can use the
expression main.X to refer to the local variable X in the procedure   main  if
you are in a routine called by main.  Note that in this example, main refers
to the main routine of a FORTRAN or C program.  It does not appear in FORTRAN
source code.

4.2.1  FORTRAN Symbols

<*> Syntax

name

A symbol is a name that represents a register, a segment address, an offset
address, or a full 32-bit address.  At the FORTRAN source level, a symbol is
simply a variable name or the name of a routine; you do not necessarily need
to know what kind of address it represents.  Note that when given as argu-
ments, symbols are never case-sensitive with the FORTRAN expression evaluator.
If you have turned on case sensitivity with the Case Sense selection from the
Options menu, it is off automatically when a symbol is used.

In assembly language output or in output from the Examine Symbols command, the
CodeView debugger displays some symbol names in the object code format
produced by the Microsoft FORTRAN Optimizing Compiler.  This format includes a
leading underscore.  For example, the main routine in your program is
displayed as _main.  Only global labels (such as procedure names) are shown in
this format.  You do not need to include the underscore when specifying such a
symbol in CodeView commands.  Labels within library routines are sometimes
displayed within a double underscore (__chkstk).  You must use leading
underscores when accessing these labels with CodeView Commands.

4.2.2  FORTRAN Constants

<*> Syntax

digits		Default radix
radix#digits	Specified radix
#digits		Hexadecimal radix

Numbers used in CodeView commands represent integer constants.  These
constants are entered in the current input radix (base).  When you are using
the FORTRAN expression evaluator, the debugger will recognize any explicitly
specified radix between 2 and 36 inclusive, as in 20#2G.  The FORTRAN radix
specifier can be used to override the current radix.  Note that a hexadecimal
number may be entered in two ways.  For example, 3F hex could be entered as
either #3F or 16#3F.  In this manual, we will use the number sign alone to
indicate hexadecimal numbers.

The default radix for the FORTRAN  version of the CodeView debugger is
decimal.  However, you can use the Radix command (N) to specify an octal or
hexadecimal radix, as explained in Section 11.3, "Radix Command."  With radix
16, it is possible to enter a value or argument that could be interpreted
either as an identifier or as a hexadecimal number.  The CodeView debugger
resolves the ambiguity by searching first for a symbol (identifier) with that
name.  If no symbol is found, the debugger jinterprets the value as a
hexadecimal number.  If you want to enter a number that overrides an existing
symbol, use the hexadecimal format (#digits).

For example, if you enter ABC as an argument when the program contains a
variable or function named ABC, the CodeView debugger interprets the argument
as the symbol.  If you want to enter ABC as a number, enter it as #ABC.

Table 4.4 shows how a sample (63 decimal) would be represented in the octal,
decimal, and hexadecimal radixes.

Table 4.4  - FORTRAN Radix Examples
----------------------------------------------
Input Radix	Octal	Decimal	Hexadecimal
----------------------------------------------
8		77	10#63	#3F
10		8#77	63	#3F
16		8#77	10#63	3F
----------------------------------------------

4.2.3  FORTRAN Strings

<*> Syntax

'string'

Strings can be specified as character expressions in the FORTRAN format.
Single quotation marks within a string must be specified by two single
quotation marks.

<*> Example

>EA MESSAGE 'This ''string'' is okay.  '

The example above uses the Enter ASCII command (EA) to enter the given string
into memory, starting at the address of the variable MESSAGE.  Notice that the
string includes embedded single quotation marks and trailing blanks.

4.2.4  FORTRAN Intrinsic Functions

When entering a FORTRAN expression, you may use a limited number of FORTRAN
intrinsic functions.  The primary use of these functions is to convert a
FORTRAN variable or value from one type to another for purposes of calcula-
tion.  The intrinsic functions recognized by the expression evaluator of the
CodeView debugger are listed in Table 4.5.  See Chapter 3 of the Microsoft
FORTRAN Compiler Language Reference for a complete description of the FORTRAN
intrinsic functions.

Table 4.5  -  FORTRAN Intrinsic Functions Supported by the CodeView Debugger
-------------------------------------------------------------------------
										Argument		Function
Name				Definition			Type			Type
-------------------------------------------------------------------------
CHAR(int)			Data-type conversion	int			char*
CMPLX(genA[,genB])		Data-type conversion	int,real,cmp	cmp8
DBLE(gen)			Data-type conversion	int,real,cmp	dbl
DCMPLX(genA[,genB])		Data-type conversion	int,real,cmp	cmp16
DIMAG(cmp16)			Imaginary part of		cmp16		dbl
				cmp16 number
DREAL(cmp16)			Data-type conversion	cmp16		dbl
ICHAR(char)			Data-type conversion	char			int
IMAG(cmp)			Imaginary part of		cmp			real**
				cmp number
INT(gen)			Data-type conversion	int,real,cmp	int
INT1(gen)			Data-type conversion	int,real,cmp	int1
INT4(gen)			Data-type conversion	int,real,cmp	int4
INTC(gen)			Data-type conversion	int,real,cmp	INTEGER[C]
LOCFAR(gen)			Segmented address		int,real,cmp	int4
LOCNEAR(gen)			Unsegmented address		int,real,cmp	int2
REAL(gen)			Data-type conversion	int,real,cmp	real4

*	The abbreviations used for the different data types in this table are listed
	in Appendix B of the Microsoft FORTRAN Compiler Language Reference.
**	If argument is COMPLEX*8, function is REAL*4. If argument is COMPLEX*16,
	function is DOUBLE PRECISION.

4.3  BASIC Expressions

The BASIC expression evaluator uses a subset of the most commonly used BASIC
operators.  It also supports one important BASIC command -- the LET command --
and one operator in addition to the BASIC operators -- the colon (:).  The
CodeView BASIC operators are listed in Table 4.6 in order of precedence.


Table 4.6  -  CodeView BASIC Operators
-----------------------
Precedence	Operator
-----------------------
(Highest)
1		()
2		.  :
3		*  /
4		\  MOD
5		+  -
6		=  <> <  >  <=  >=
7		NOT
8		AND
9		OR
10		XOR
11		EQV
12		IMP
13		LET...=
(Lowest)

The BASIC expression evaluator does not support the exponentiation operator
(^).  Nor does it support string assignment, the string concatenation oper-
ator (+), or any of the relational operators (=, <, >, etc.), when used with
strings.  However, arrays, records, and user-defined types are all supported.

The order and precedence with which the CodeView debugger evaluates BASIC
expressions are the same as in the Microsoft BASIC language.  See your Basic
documentation for a description of how BASIC operators can be combined with
symbols and constants to form expressions.
---------
Important
---------
The BASIC expression evaluator supports arrays and array indexing but not
multidimensional arrays.  This is a limitation only of the BASIC express
ion evaluator and does not apply to the other languages.
=========

The assignment operator LET is supported for numerical operations only.  When
you use LET in a BASIC expression, the return value will not be useful.
However, an assignment will take place whenever the expression is evaluated.
This gives you a convenient way of manipulating data.  For example, after the
expression LET A = 5 is evaluated, the variable A will contain the value 5.
You must use the keyword LET to specify assignment; otherwise, the BASIC
expression evaluator will interpret the equal sign ( = ) as a test for
equality.

The colon operator (:) may be used to specify a memory address.  It acts as
a segment:offset separator, as described in Section 4.7.2,
"Addresses."

In the CodeView debugger, the period (.) has an extended use as a specifier of
local variables in parent routines.  The syntax is shown below:

routine.variable

The routine must be a high-level language routine and the variable must be a
local variable within the routine.

When a BASIC expression is used as an argument with a command that takes
multiple arguments, the expression should not have any internal spaces.  For
example, COUNT+6 is allowed, but COUNT + 6 may be interpreted as three
arguments.  Some commands (such as the Display Expression command) only take
one argument; these commands do permit spaces in expressions.

4.3.1  BASIC Symbols

<*> Syntax

name

A symbol is a name that represents a register, a segment address, an offset
address, or a full 32-bit address.  At the BASIC source level, a symbol is
simply a variable name or the name of a routine; you do not necessarily need
to know what kind of address it represents.  With the BASIC expression evalu-
ator, symbols follow the naming rules of the BASIC compiler.  In particular,
all the type specifiers used in BASIC ($, %, &, !, and #) are accepted by the
BASIC expression evaluator.  Note that symbols are never case sensitive to
BASIC, whether the Case Sense option is on or not.

4.3.2  BASIC Constants

<*> Syntax

fixed-point-string[#|!]		Single or double, fixed-point format
floating-point-string[#|!]	Single or double, floating-point format

digits					Integer, default radix
&Odigits					Octal radix
&digits					Alternative octal radix
&Hdigits					Hexadecimal radix

With the BASIC expression evaluator, numbers can be entered as integer, long,
single precision, or double precision data objects.  Constants are formed
according to the rules of the Microsoft BASIC Compiler.  A single or double
precision constant must be entered in decimal radix, regardless of the current
radix.  To enter a single or double, use the Microsoft BASIC rules for forming
fixed and floating point strings.

Integer constants are entered in the system radix and are made up of octal,
decimal, or hexadecimal digits.  You may override the system radix by using
the octal or hexadecimal prefix.  In addition, you can use the & suffix on any
integer constant to indicate that the integer is to be stored as a long (four-
byte) integer, rather than as a short (two-byte) integer.  To enter integers
in the decimal format, the system radix must be 10, and you use the default
radix.  There is no way to enter decimal integers when the system radix is
other than 10, unless you switch to another expression evaluator.
 The default radix for the BASIC expression evaluator is decimal.  However, you
can use the Radix command (N) to specify an octal or hexadecimal radix, as
explained in Section 11.3, "Radix Command."
With radix 16, it is possible to enter a value or argument that could be
interpreted eithr as an identifier or as a hexadecimal number.  The CodeView
debugger resolves the ambiguity by searching first for a symbol (identifier)
with that name.  If no symbol is found, the debugger interprets the value as a
hexadecimal number.  If you want to enter ABC as a number, enter it as &HABC.

Table 4.7 shows how a sample number (63 decimal) would be represented in the
octal, decimal, and hexadecimal radixes.
Table 4.7  BASIC Radix Examples
----------------------------------------------
Input Radix	Octal	Decimal	Hexadecimal
----------------------------------------------
8		77	-	&H3F
10		&077	63	&H3F
16		&077	-	3F

4.3.3  BASIC Strings

The BASIC expression evaluator does not allow you to input strings while
debugging.  However, it does recognize both fixed and variable length string
variables, as defined by the BASIC compiler. (This includes arrays and records
of strings.)  Expressions that refer to strings will probably be quite simple,
because string operators (concatenation and relational operators) are not
supported by the BASIC expression evaluator.

By using the Enter Address command, you can enter a string literal at a given
address.  To use this technique effectively, however, you will need to under-
stand how BASIC handles string variables.  For more information, see Chapter
6, "Examining Data and Expressions."

4.3.4  BASIC Intrinsic Functions

When entering a BASIC expression, you may use a limited number of BASIC
intrinsic functions.  The primary use of these functions is to convert a BASIC
variable or value from one type to another for purposes of calculation.  The
intrinsic functions recognized by the expression evaluator of the CodeView
debugger are listed in Table 4.8.  See your BASIC compiler manual for a
complete description of the BASIC intrinsic functions.

Table 4.8 - BASIC Intrinsic Functions Supported by the CodeView Debugger
-------------------------------------------------------------------------
						Argument				Function
Name		Definition			Type					Type
-------------------------------------------------------------------------
ASC*		ASCII value of			string				integer
		first character
CDBL		Data-type conversion	numerical expression	double
CINT		Conversion, with		numerical expression	integer
		rounding
CSGN		Data-type conversion	numerical expression	single
CVI		Data-type conversion	two-byte string		integer
CVL		Data-type conversion	four-byte string		long
CVS		Data-type conversion	four-byte string		short
CVD		Data-type conversion	eight-byte string		double
FIX		Conversion, with		numerical expression	integer
		truncation
INT			Conversion, with		numerical expression	integer
			truncation
LBOUND(arr[,dim])	Lowest index		array, dimension		integer
			of array
UBOUND(arr[,dim])	Highest index		array, dimension		integer
			of array
VAL			Numerical value of		string				integer, long,
			string									single, double
VARPTR		Offset of variable		variable name			integer
VARSEG		Segment of variable		variable name			integer

* Except where noted, each of the functions in this table takes exactly one
  argument of the type indicated in the third column.

.end of first half.


